Phase 1: Adding documentation metadata tags #6274
Conversation
✅ Deploy Preview for knative ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
knative-prow
bot
added
the
size/L
knative-prow
bot
added
the
approved
|
https://diataxis.fr/complex-hierarchies/#two-dimensional-problems may be helpful when figuring out how to structure these eventually. |
knative-prow
bot
added
size/XXL
|
@dwelsch-esi -- PTAL (please take a look), as this should help (hopefully) with the initial phase of techdocs assessment. If this makes sense to you, then you can reply with |
|
@evankanderson, Just one minor question regarding audience: The same page can be relevant to more than one audience. Looks like you've inserted comments to that effect in some of the files, for example Is there a reason you didn't make this field a list like you did for components? Regardless, I don't think this is a big deal -- I'm sure the role you've identified in each case is the primary audience for the page. If the meta tags become super important later, you could open another PR to update them, but I don't think this question is worth holding up the merge. /lgtm |
|
@dwelsch-esi: changing LGTM is restricted to collaborators In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
Generally, I'm suspicious of trying to target more than one audience or purpose in a single document. In cataloguing our current docs, we do mix these audiences, but I would probably prefer to move a bunch of the installation docs separate from the usage docs, rather than encourage this mixing. |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: Cali0707, evankanderson The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
* Add metadata tags for documentation * Add classification for about 2/3rds of docs (func + eventing) * Add classification for remainder of docs (serving+install)
* Phase 1: Adding documentation metadata tags (#6274) * Add metadata tags for documentation * Add classification for about 2/3rds of docs (func + eventing) * Add classification for remainder of docs (serving+install) * Add mermaid support (#6327) * Publish threat model in documentation (#6263) * Publish threat model in documentation * Separate security contents a bit more, update link to threat model, update nav * Add a section on supply chain and SBOM/SLSA mitigation * Update threat model with feedback from David Hadas * Update introduction with content from davidhadas, add sections on controller and webhook functionality and update targets of threats * content tab fixes, added success output for kn func (#6367) * Add dry run section and take out old feature flag in serving (#6366) * add dry run section * drop mention of old feature flag * fix casing on nav * update docs to be more clear and include inline example --------- Co-authored-by: Dave Protasowski <[email protected]> * Attempt to rebuild docs build process, inspired by #6319 (#6371) * Attempt to rebuild docs build process * Use a more modern python version * Fix strict verify, hide versions on unversioned pages * Fix search with mkdocs typescript patches (vendored). (#6392) Hopefully, this can be fixed upstream via PR shortly. * Installation Doc Updates (#6395) * Installation Doc Updates Improve installation guidance * Formatting fix * Update docs/install/README.md link fix Co-authored-by: Evan Anderson <[email protected]> * Update docs/install/README.md link fix Co-authored-by: Evan Anderson <[email protected]> * link fix and table update More writing * Update README.md Misc edits * Update README.md Minor edits * Adding install-kn to PR Consolidating CLI installations into this this topic. * Update install-kn.md Changing red bug alert to important The old syntax was: ??? bug "Having issues upgrading `kn` to Homebrew?" * Update install-kn (snippet) Removed alert formatting * Added quickstart-install.md Various edits * Fixes and reviewed edits Made Evan suggestions, table column test, spelling fixes * Update quickstart-install.md link fix * Update README.md Replaced the table with a bulleted list approach. * Update README.md Put back the table * Added serving and eventing install topics Updated topics per effort - consolidating guidance * Link fixes * Made Evan's edits * Various updates All files added for this PR. * Link fix * Formatting fixes * Formatting and consistency fix * Update docs/install/operator/knative-with-operator-cli.md Co-authored-by: Evan Anderson <[email protected]> * Update docs/client/install-kn.md Co-authored-by: Evan Anderson <[email protected]> --------- Co-authored-by: Evan Anderson <[email protected]> * Fix edit page links, move technical docs under sub-heading (#6398) * Fix edit links by moving docs content under a dedicated subdirectory * Fix edit links by moving docs content under a dedicated subdirectory * Add High availability documentation section for eventing (#6401) I have copy-pasted from the Knative Serving documentation page the block as I found it missing when configuring it. * Update proc-running-function.md (#6400) Undo separeate kn func output for invoke * Add a note that Apache Kafka is required to use EKB (#6404) * Move install docs to administration (#6403) * Fix trailing newline complaints * Fix redirects from #6398 --------- Co-authored-by: Bruce Hamilton <[email protected]> Co-authored-by: Alexander-Kita <[email protected]> Co-authored-by: Dave Protasowski <[email protected]> Co-authored-by: Aurélien Joga <[email protected]> Co-authored-by: Christoph Stäbler <[email protected]>
3 participants
Proposed Changes
In preparation for a CNCF TechDocs Assessment, start labelling Knative documentation with metadata to assist with re-organizing content to different information architecture options (we will still need manual review, but this may simplify that review).
I'm using a schema with 3 fields:
audiencedeveloper,administrator,buyer,contributorcomponentseventing,functions,serving(list)functionmarketing,community,tutorial,how-to,reference,explanation